************************
* JFREEREPORT 0.8.7-6  *
************************

27 July 2006

1. INTRODUCTION
---------------
JFreeReport is a free Java report library, distributed under the terms
of the GNU Lesser General Public License (see license-LGPL.txt for
details).  JFreeReport is developed by Thomas Morgner, David Gilbert
and others.

For the latest news and information about JFreeReport, please refer to:

    http://www.jfree.org/jfreereport/


2. DOCUMENTATION
----------------
A complete documentation for JFreeReport's simple XML file format has
been written by Pentaho and is available from Pentaho's SourceForge
project page.

http://prdownloads.sourceforge.net/pentaho/Pentaho_Advanced_Reporting_Guide_1.1.7.pdf?download.


The Pentaho Report Design Wizzard and the Pentaho Report Designer provide
some easy means to edit XML-based report definitions.

These tools can be downloaded from:

http://www.pentaho.org/download/


3. CONFIGURATION
----------------
JFreeReport can be configured by placing a jfreereport.properties file into
the root of the classpath. Modifying the supplied properties file in the
package org/jfree/report has no effect, as this is the final fallback
file and every other report configuration source will be preferred over this
file.

To edit the properties file, you may use the graphical configuration editor
from the module "gui-config". The editor can be started by calling

  java -jar jfreereport-gui-config-0.8.7-6.jar


4. RUNNING THE DEMO
-------------------
The demo for JFreeReport can be started with

  java -jar jfreereport-demo-0.8.7-6.jar


5. OTHER LIBRARIES
------------------
JFreeReport uses several other open source libraries:

  JCommon   - http://www.jfree.org/jcommon/
  Pixie     - http://www.jfree.org/jfreereport/pixie/
  LibFonts  - http://www.jfree.org/jfreereport/libfonts/
  LibLoader - http://www.jfree.org/jfreereport/libloader/

If you want to use the bean shell module, you will need:

  BeanShell - http://www.beanshell.org/

The XML parser and writer require at least an JAXP-1.1 compatible
parser. JDK 1.4 or higher already contains a suitable parser, for
all other JDKs you will need an additional package, for instance:

  GnuJAXP - http://www.gnu.org/software/classpathx/jaxp/

The RTF or PDF support requires the iText library (version 1.4 or higher):

  iText - http://www.lowagie.com/iText/

The Excel export requires the Apache POI library (version 3.0-alpha1 or higher)

  POI - http://jakarta.apache.org/poi/


6. JAVADOC HTML PAGES
---------------------
The Javadoc HTML pages for JFreeReport are available on-line at the
JFreeReport home page.  You can also regenerate the Javadocs directly
from the source code.  There is a task in the Ant script (see below)
that makes this relatively simple.


7. EXTENDED XML DEFINITION REFERENCE DOCUMENTS
----------------------------------------------
The reference documents for the extended report definition format can
be generated by starting the java class

  org.jfree.report.modules.misc.referencedoc.ReferenceDocGenerator

or by starting the misc-referencedoc module with

  java -jar jfreereport-misc-referencedoc-0.8.7-6.jar

The reference manual documents all currently defined StyleKeys and
the object definitions used in the stylekeys and when defining
templates or datasources.


8. SUPPORT
----------
Free support is available via the JFreeReport forum, follow the link
from the JFreeReport home page.  Please note that questions are
answered by volunteers, so there is no guaranteed response time or
level of service.

Please avoid e-mailing the developers directly for support questions.
If you post a message in the forum, then everyone can see the
question, and everyone can see the answer.

Commercial support and consulting is available from Pentaho.
(http://www.pentaho.org/)


9. REPORTING BUGS
-----------------
If you find bugs in JFreeReport, we'd like to hear about it so that we
can improve future releases of JFreeReport.  Please post a bug report
at the JFreeReport project page on SourceForge:

    http://sourceforge.net/projects/jfreereport

Please be sure to provide as much information as you can.  We need to
know the version of JFreeReport that you are using, the JDK version,
and the steps required to replicate the bug.  Include any other
information that you think is relevant.


10. ANT
------
We use an open source build tool called Ant to build JFreeReport.  An
Ant script (tested using Ant 1.5.4) is included in the distribution:

    <jfreereport-directory>/ant/build.xml

You can find out more about Ant at:

    http://ant.apache.org/

Ant is licensed under the terms of the Apache Software License (a
popular open source software license).


11. CHECKSTYLE
-------------
We use a free utility called Checkstyle to apply a consistent coding
style to the JFreeReport source code.  You will find the Checkstyle
property settings in the following file:

    <jfreereport-directory>/checkstyle/checkstyle.xml

These rules require Checkstyle 3 or higher.

You can find out more about Checkstyle at:

    http://checkstyle.sourceforge.net/

Checkstyle is licensed under the terms of the GNU LGPL.


12. TABLE-BASED OUTPUTTARGETS AND PLAINTEXT-OUTPUT
-------------------------------------------------

All table based output targets (HTML, Execl, Layouted CSV) have some
layout restrictions. These layout restrictions also apply to the
PlainText output target:

* The elements must be aligned properly, they must not overlap. When
  overlapping, the left element gets preferred over the right element,
  and top elements have a higher preferrence level as bottom elements.

* The elements must be large enough to contain the element. This is
  important when specifying the cell/line height, the elements height
  must be greater than the minimum height.

  For Excel/Html cells the minimum height is equal to the font height,
  so you'll just have to make sure that the cell is able to print at
  least one line of text.

  For PlainText, the line height is defined by the LPI setting, if LPI
  (lines per inch) is set to 10, then the minimum height of a line
  should be 72/10 points, so specifying a element height of 8 is safe.
  If LPI is set to 6, then the line height should be at least 72/6, so
  a element height of 12 should be ok.

* The Epson- and IBM plain text output does not handle 16-bit character
  sets. When using the PlainText output target to send the output to an
  printer, make sure that your printer is able to handle the used text
  encoding. 

* When specifying colors for the Excel target, then these colors are
  translated into one of the predefined excel color constants. This
  translation tries to find the nearest color, if that fails, the colors
  could look weird. Using one of the predefined AWT colors is always safe,
  everything else should work, but there are no guarantees.


13. DEFINING THE SELECTABLE ENCODINGS IN THE EXPORT DIALOGS
-----------------------------------------------------------
By default, the export dialogs make all defined string encodings available
in the encodings comboboxes. As the availability of all encodings is not
necessary for most deployment scenarios, we implemeted a way to customize
the available encodings.

The general availabilty can be defined by specifying the report configuration
key "org.jfree.report.modules.gui.base.EncodingsAvailable". If the key is
set to "all", then all supported encodings of the JDK are enabled and
selectable. Setting the key to "none" will disable the encodings completly,
and only the report's defined target encoding is visible and selectable.

If the configuration key is set to "file", then a encodings property file can
be specified with the configuration key
"org.jfree.report.modules.gui.base.EncodingsFile". The key should point to a
properties file, which contains all selectable encodings. A sample for such
a property file can be found as resource
"/org/jfree/report/modules/gui/base/components/jfreereport-encodings.properties"
in the library and the sources.


14. "BUGGY FONTRENDERER CONTEXT" MESSAGE APPEARS IN THE LOGS
------------------------------------------------------------
A message like this one appears in the logs:

  DEBUG: This is a buggy version of the font-renderer context: false
  DEBUG: The buggy-value is defined in the configuration : false
  DEBUG: The G2OutputTarget uses Antialiasing.
  The FontRendererBugs should not be visible in TextAntiAliasing-Mode.
  If there are problems with the string-placement, please report your
  Operating System version and your JDK Version to www.object-refinery.com/jfreereport.

This is a debug message, so (as with every debug message) it may have
no meaning at all. But this one has .. :)

  DEBUG: This is a buggy version of the font-renderer context: true
  DEBUG: The G2OutputTarget uses Antialiasing.

means, that your AWT implementation behaves different when
fonts are rendered with aliasing enabled than it would do
without aliasing. Most Sun JDKs have this bug, which got
finally fixed in JDK >1.4.

The FontMetrics implementation is not correct, when Aliasing
is disabled (the computed font size is not the same as the
used space when printing the string). In that case, we just
use our own FontMetrics calculation methods, and it seems to
work...

But our method is not foolprof, as it is no standard
function, and it is possible, that our fix may not work on
other JDKs or may cause the layout be get even more weird.
So if your layout looks weird and text elements behave
strangely, then you should report your JDK version and
OperatingSystem to us. If everything looks fine, then ignore
the message ...

If this bug strikes you, you will see that non-left aligned texts
are printed on wrong positions, while left-aligned text does not
fully use the available space (or the oposite effect, that the field
does not obey to the defined limitations).


15. USING TRUETYPE FONTS
------------------------
Unix: If you want to use TrueType in Java, you will have to copy all
  needed TrueType fonts to the $JRE/lib/fonts directory. After copying
  the fonts, make sure that you update the font.dir file of that directory,
  so that the JRE can find these fonts.

  When JFreeReport is used to generate PDF files only, copying the files
  will not be necessary, iText uses the all fonts of the default font path
  without using AWT functionality.

  The PDF-Target will register all fonts found in the directory
  "/usr/X11R6/lib/X11/fonts" and all subdirectories. Additionally the directory
  "/usr/share/fonts" is searched for usable font files.

  See also: (This should also work for JDK 1.2.2)
  http://java.sun.com/j2se/1.3/docs/guide/intl/addingfonts.html#adding

MacOS: The iText library uses only TTF and Adobe font files to generate PDF
  files. If your system stores the fonts in the ResourceFork, Java may not be
  able to access them.

  You can use FONDU (http://fondu.sourceforge.net/) to convert the MacOS fonts
  into a usable format.

  Additionally the MacOS X font directories are searched in the following order:

  ~/Library/Fonts
  /Library/Fonts
  /Network/Library/Fonts
  /System/Library/Fonts

  Any TTF, AFM or PFB file found in these directories will be registered with
  iText and can be used to create PDF files.

Windows: The %WINDIR%/fonts directory is used to search and register the system
  fonts. The JDK uses all fonts that are available, no additional work is needed.


16. STRICT FLOATINGPOINT WARNING
--------------------------------
Since Java 1.2 Virtual Maschines are free to implement a relaxed floating
point arithmetics, which increases the exponent size.

This kind of arithmetics seems to break the PDF generation in JFreeReport.
The generated documents have missing characters while the Graphics2D output
is perfectly.

If the non-strict floatingpoint arithmetics is enabled on the VM running
JFreeReport, the following warning will be printed:

WARN: The used VM seems to use a non-strict floating point arithmetics
WARN: Layouts computed with this Java Virtual Maschine may be invalid.
WARN: JFreeReport and the library 'iText' depend on the strict floating
WARN: point rules of Java1.1 as implemented by the Sun Virtual Maschines.
WARN: If you are using the BEA JRockit VM, start the Java VM with the option
WARN: '-Xstrictfp' to restore the default behaviour.

At the moment, this behaviour seems to be limited to the JRockit VM from
BEA, as this is the first VM implementation that uses this feature.
The default floating point behaviour of Java 1.1 can be restored using
the virtual maschine flag '-Xstrictfp' when starting the Java VM.


17. OTHER FEEDBACK
-----------------
For other feedback and comments, please post a message on the
JFreeReport forum. The Forum is available at

  http://www.jfree.org/phpBB2/viewforum.php?f=8
